home *** CD-ROM | disk | FTP | other *** search
/ Complete Linux / Complete Linux.iso / docs / apps / database / postgres / postgre2.z / postgre2 / doc / implementation / frontend-proto < prev    next >
Encoding:
Text File  |  1992-08-27  |  10.3 KB  |  312 lines
  1. .\"----------------------------------------------------------------------
  2. .\" FILE
  3. .\"    frontend-protocol.t
  4. .\"
  5. .\" DESCRIPTION
  6. .\"    Specification for the IPC protocol between the frontend and 
  7. .\"    backend processes.
  8. .\"
  9. .\" RCS ID:
  10. .\"     $Header: /private/postgres/doc/implementation/RCS/frontend-protocol.me,v 1.1 1990/07/30 13:50:21 kemnitz Exp $
  11. .\"----------------------------------------------------------------------
  12. .fo ''%''
  13. .ce 2
  14. Communication Procotol between the Frontend and POSTGRES Backend
  15. (Version of: $Date: 1990/07/30 13:50:21 $)
  16. .sp
  17. .sh 1
  18. Communication 
  19. .sh 2
  20. Communication Ports
  21. .pp
  22. A frontend communicates to the POSTGRES backend using IPC ports.  
  23. There are two ways to specify the communication port: 
  24. (1) the environment variable PGPORT; 
  25. (2) the optional argument \fI-p port\fP to the terminal monitor.
  26. If PGPORT and \fI-p port\fP specify different ports, 
  27. the one specified by \fI-p port\fP
  28. is used.
  29. If no port is specified, a default port (currently 4321) is used.
  30. Ports other than the default port is used mostly for debugging.
  31. .sh 2
  32. Initialization of the Communication
  33. .pp
  34. When the communication starts, the frontend passes a string (referred to as
  35. \fIinit string\fR thereafter) to the postmaster.  The postmaster
  36. processes the init string, starts up a backend, and 
  37. initialize the backend with the init string.  The init string
  38. is in the format:
  39. .(l
  40. init string:    user-name,database,tty,[pgoption] <newline>
  41. user-name:    the user's login
  42. database:    the database to access
  43. tty:        the tty in which the backend debugging message is displayed,
  44.         default is /dev/null, used for debugging.
  45. pgoption:    optional arguments
  46. .)l
  47. A typical init string is:
  48. .(l
  49. "ywang,ywang,/dev/ttyp4,<newline>"
  50. .)l
  51. .pp
  52. A user could be registered with a password.  However, password is not
  53. required for every user.  When users are registered with the POSTGRES
  54. manager, they can decide whether they want to use passwords.
  55. .pp
  56. Having received the init string, the backend checks:
  57. (1) if the user is not a valid POSTGRES user,  send a \fIdeny\fP 
  58. message back;
  59. (2) if the user is registered with a password, ask the frontend for
  60. the password;  if the password supplied is not correct, send a \fIdeny\fP
  61. message to the frontend;
  62. (3) if the user does not have access to the database specified, send back
  63. a \fIdeny\fP message; 
  64. (4) if all three tests are successful, send back an \fIauthorization\fP 
  65. message.
  66. .pp
  67. The message from backend to frontend:
  68. .(l
  69. ask for password:    W
  70. authorize:    Y <backend_pid> <verification#>
  71.         <backend_pid> is the pid of the backend process
  72.         <verification#> is a code used when abortion is requested
  73. deny:        N <errorcode> <errormsg>
  74.         <errorcode> and <errormsg> are defined in Section 4.
  75. .)l
  76. The message from frontend to backend:
  77. .(l
  78. send password:    W <password>
  79. .)l
  80. we will use a protected port for communication, so the <password> will be
  81. transferred as a string.  The backend will then encrypt it and compare with
  82. the encryption stored in the USER relation.
  83. .pp
  84. If the backend sends a Y to the frontend, the communication has been 
  85. established, the
  86. frontend may start sending queries for execution.  If the backend sends
  87. an N to the frontend, it will terminate the communication at the same time, 
  88. the frontend
  89. can either quit or repeat the above process with a different init string.  
  90. .sh 2
  91. Optional Arguments
  92. .pp 
  93. These optional arguments can also be executed as a function.
  94. .(l
  95. command = yes
  96.     Return the query command
  97. append_oid = yes
  98.     return the oid of the appended tuple (only when a single tuple is appended)
  99. number_tuples = yes
  100.     return the number of tuples updated (replaced, deleted, etc.)
  101. max_length = nbytes
  102.     truncate large data objects to nbytes when retrieving or fetching.
  103. blank_fetch = yes
  104.     fetch all the qualified tuples when retrieve into blank portal, if
  105.     this is not set, no tuple is returned until the first fetch.
  106. blank_ascii = yes
  107.     transfer tuples from a blank portal in binary format.
  108. data_ascii = yes
  109.     transfer tuples from data portal in ASCII format.
  110. network = yes
  111.     convert binary values to network byte-ordering during transfer.
  112. .)l
  113. .sh 2
  114. Status
  115. .pp
  116. The init string (except optional arguments) 
  117. has been implemented, but nothing else.
  118. An error with the init string is not reported until the first query
  119. is sent to the backend.
  120. .sh 1
  121. Executing Queries
  122. .pp
  123. After the frontend has been authorized to access the database, 
  124. it can send queries
  125. to the backend for execution.  
  126. POSTGRES supports two kinds of \fBportals\fP:
  127. blank portals and data portals.  
  128. Usually blank portals are used by the terminal monitor, data portals
  129. used by more sophisticated frontend applications.
  130. .sh 2
  131. Messages from Frontend to Backend
  132. .(l
  133. to send a query:        Q <xactid> <query>
  134. to execute a function:    F <function_name> <arg_list>
  135. .)l
  136. .sh 2
  137. Messages from Backend to Frontend
  138. .(l
  139. to signal an error:    E <xactid> <errorcode> <line#> <column#> <errormsg> 
  140.     line# and column# is where the error occurred within the query
  141.  
  142. successful query:    {portal} command
  143. portal:        P/A <xactid> <pname> {tuple_group} Z
  144. tuple_group:    T <nfields> {tupe_info} {tuple}
  145. tupe_info:    <fname> <adtid> <adtsize>
  146. tuple:        D <bitmap> <tuple_length> {value}
  147. value:        [<value_length>] <value_block>
  148.         value_length is the number of bytes in the value-block.
  149.         a value_length only precedes a variable size data object.
  150. command:    C <xactid> <command> return-values Z
  151. return-values:    [O <oid>] [N <no_tuples>]
  152. note that {R <remark>} can appear before any identifiers. 
  153. .)l
  154. .pp
  155. A successful function execution may return a primitive value, a group of
  156. tuples, or even a portal.  The protocol for portal and tuples should be
  157. similar to what described above.  The primitive value returned is:
  158. .(l
  159. function_value:    V <value_length> <value_block>
  160. .)l
  161. The frontend should know how to interpret these values.  A set of functions
  162. need to be added to LIBPQ for handling of function execution.
  163. .pp
  164. We may want to group the return values from backend into large blocks to
  165. save the network transmission cost.  But this will not happened soon.
  166. .sh 2
  167. Status
  168. .pp
  169. Query execution and tuple returning (except <tuple_length>) 
  170. have been implemented.  Binary data transfer has not been 
  171. implemented yet.  Nothing is
  172. there to support execution of functions. Returning of oid and no_tuples
  173. have not been implemented yet.  The identifier Z is not there.
  174. We still need to figure out the syntax for arg_list.
  175. .sh 1
  176. Messages from Frontend to Postmaster
  177. .pp
  178. The frontend may need a second socket connected to the same backend
  179. (we may live without a second socket).
  180. The frontend definitely need someway to abort a transaction.  Postmaster
  181. has two ports, one is for the start up of communication, the other one is
  182. a datagram port receiving and processing packages sent to it.  The datagram
  183. port can be used to implement the abortion facility.  However, it needs a 
  184. considerable amount of work to get abortion to work.
  185. .(l
  186. to ask for a socket:     S
  187. to abort a xact:        B <backend_pid> <verification#>
  188. .)l
  189. In both cases, the backend should send back some message.  
  190. .pp
  191. Nothing discussed in this section has been implemented. 
  192. .sh 1
  193. Definitions of Terms
  194. .(l
  195. string:        strlen characters
  196. strlen:        int[4]
  197.         is the number of characters in the string, not including the
  198.         4 bytes in strlen.
  199. string[n]:    string with a max length of n
  200. backend_pid:    int[4]
  201. verification#:    int[4]
  202. errorcode:    int[2]
  203.         is the code of the error.  Each code represents one kind
  204.         of error.  The errormsg will only pass the arguments of 
  205.         the error.
  206. errormsg:    string[80]
  207.         error messages sent by the backend
  208. password:    string
  209. xactid:        int[5]
  210.         is the transaction id of the current transaction. 
  211.         we do not know at this point how xactid will be used.
  212. query:        string
  213.         is the query sent to the backend
  214. function_name:    string
  215.         is the name of the function to be invoked
  216. arg_list:        some binary format
  217. line#:        int[4]
  218. column#:    int[4]
  219. remark:        string[80]
  220.         are the remarks sent by the backend, the frontend just drops
  221.         it on the floor right now, could be used later on.
  222. pname:        string
  223.         is the portal name
  224. fname:        string
  225.         is the field (attribute) name
  226. nfields:        int[2]
  227.         is the number of fields (attributes) in the tuples.
  228. adtid:        int[4]
  229.         is the adtid of a data type
  230. adtsize:        int[2]
  231.         is the number of bytes of a data type.
  232.         -1 if the type is of variable size.
  233. bitmap:        int[n] where n = ceiling(nfields/8)
  234.         is the bitmap of a tuple.  Bitmap is sent 4 bytes at a time.
  235. tuple_length:    int[4]
  236. value-length:    int[4]
  237.         value_length is the number of bytes in the value-block, not
  238.         including the 4 bytes of itself.
  239. value_block:    a stream of bytes
  240. command:    string[20]
  241.         is the query command passed from the backend, such as
  242.         retrieve, fetch, etc.        
  243. oid:        int[4]
  244. no_tuples:    int[4]
  245. identifier:    a single char
  246.         an identifier always precedes the information being passed.
  247. .)l
  248. .sh 1
  249. Identifiers
  250. .(l
  251. W:    ask for password
  252. Y:    frontend authorized
  253. N:    frontend denied
  254. Q:    query (from frontend to backend)
  255. F:    to execute a function
  256. E:    error message
  257. P:    synchronized portal
  258.     a synchronized portal is a normal portal specified in the user's
  259.     query command.
  260. A:    asynchronized portal
  261.     an asynchronized portal is a portal defined by rules, which are
  262.     triggered when a query is executed.
  263. T:    type information
  264.     the type block for a tuple group
  265. D:    a tuple
  266. C:    query command executed (from backend to frontend)
  267. Z:    end of an information block
  268. R:    remarks
  269. S:    asking for a socket
  270. B:    abort a xact
  271. .)l
  272. .sh 1
  273. Implementation Plan
  274. .sh 2
  275. Version 1
  276. .pp
  277. To implement data portal, we need two functions to convert byte ordering.
  278. All other code is in ~postgres/src/util/{printtup.c, dumptup.c, pcomm.c}.
  279. To add oid to the backend would cost two weeks of Serge's time.
  280. .sh 2 
  281. Version 2
  282. .pp
  283. What will go into Version 2 has not been decided yet.
  284. .sh 1
  285. Notes
  286. .(l
  287. 1. POSTGRES is currently a SINGLE user system.  Therefore oid's allocated by
  288.    different backends may not be unique.  
  289. 2. all integers transferred between frontend and the backend should first
  290.    be converted to network byte ordering, and then changed back when received.
  291. 3. what should be done with very large data objects? 
  292.    anything the frontend thinks appropriate.
  293. 4. how to append or replace tuples with binary attributes?
  294.    use fast path.
  295. 5. how to execute a function from TM?
  296.    use \\f.
  297. 6. <function_name> is currently char16.
  298. .)l
  299. .sh 1
  300. Future Extensions
  301. .(l
  302. 1. help for database schema similar to the "help" in INGRES.
  303. 2. friendly error message.
  304. 3. a frontend "help" about backslash commands.
  305. 4. after an update query, print out the #tuples updated.
  306. .)l
  307. .sh 1
  308. Issues
  309. .(l
  310. 1. number of portals which can be open at the same time (currently 3 or 4).
  311. .)l
  312.